---
author: ryyppy
date: "2020-05-12"
previewImg: /blog/archive/state-of-reasonml-org-q2-2020.avif
title: State of reasonml.org 2020-Q2 / Pt. 3
description: |
  A report on recent achievements in the reasonml.org project. In this part we
  talk about upcoming tools and features.
---

## Future Tools for the Community

In [Part 2](./state-of-reasonml-org-2020-q2-pt2.mdx) we've talked about automated

This article will cover some features and exciting ideas we have been working on for quite a while now. Even though these features are not fully implemented yet, we still think it's important to communicate the whole spectrum of the project.

## Generating Full API Docs

As we already mentioned in our previous posts, the API documentation is currently maintained by hand, and we only offer documentation for the `Js` and `Belt` module, since they are the most relevant for BuckleScript development.

This will change as soon as our [doc-tools](https://github.com/reason-association/doc-tools) are ready to be used.

The `doc-tools` project includes a CLI that enables us to easily run the odoc toolchain on the BuckleScript repository to generate JSON data, which will be our foundation for statically generated, good looking, and interactive doc pages within NextJS (see [SSG](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation)). The project is managed and developed by [rizo](https://github.com/rizo). You can find more information about it [here](https://www.reason-association.org/projects/doc-tools).

We are aware that there is more software doing similar things, such as `redoc` or `bs-doc`, the latter acting as the driver for odoc within a BuckleScript project. Since our goal is to have a battle-tested, well-integrated and easy to use tool for odoc JSON generation, we will first start testing `doc-tools` by generating the API docs for `reasonml.org` before making it available to the broader community.

As soon as we figured out the details (e.g. the right JSON data model), we will have a better idea on how to build useful infrastructure around it. For instance, we thought about designing a customizable ReasonReact component library that allows consumers to build their own custom odoc data based UI for their own projects.

There's a lot of potential, but one needs to think about easy to use API design first and then test it thoroughly before public release.

## Search

We don't have any **search functionality** yet, and this will take some more time to implement. We looked for indexing services that can cover both, the prose text and API documentation to put search results in a more refined context.

There were some solutions, but still, Algolia turned out to be the best candidate with its smallest pricing tier. We don't want to rely on the Algolia OSS webscraping API, since it doesn't give us enough control on manipulating the search results, and we need more control if we want to be able to design a custom search experience.

<Image
  src="/blog/archive/search-mockup.avif"
  withShadow={true}
  caption="A unified search overlay mockup for prose & API content"
/>

We did the ground work for our search feature and we will get into more detail as soon as we are able to generate API docs with our aforementioned `doc-tools`. Like with the API docs, we'll first need the doc-tools infrastructure so we can generate indexable data for Algolia as well.

## Playground

We also invested a lot of time into thinking about the future of the Reason playground from a UX perspective. Our most important goal is to make it possible to switch BuckleScript versions on demand. We also wanted the relevant Reason version to be part of the playground bundle.

<Image
  src="/blog/archive/playground-mockup.avif"
  withShadow={true}
  caption="UI mockup for the new playground (Desktop version)"
/>

Users should always know what version of BuckleScript / Reason is running when writing and sharing code, and the code written on a playground should be runnable with an equivalent bs-platform setup on a local machine. Right now, `reasonml.github.io/try` uses different refmt.js / playground bundle versions, which makes it really hard to write reproducible code for the same BuckleScript version.

Switchable BuckleScript versions will help tremendously with the testing process for new BuckleScript beta releases. Within BuckleScript, we already started integrating the Refmt API into the bucklescript js_of_ocaml entry-point and refactoring the bundle API to access Reason / BuckleScript version more easily. In the next step we will start implementing the Playground web-app on `reasonml.org/try`. You can find the mockups here: [Desktop](https://xd.adobe.com/spec/1cd19c3a-a0bb-4f93-4e11-725589888696-6ae0/screen/e8559ac4-5e35-430b-83f3-e4ad8c1e274c/Reason-1400-Playground) / [Mobile](https://xd.adobe.com/spec/1cd19c3a-a0bb-4f93-4e11-725589888696-6ae0/screen/adfe80dc-6bc1-40a5-9975-aa062e63cdc5/Reason-Playground).

Design & UX will play an important role here. Users should be able to use the playground on a mobile device as well, making the process of sharing / editing code snippets, while on the go, way easier.

## Conclusion

You now know what new features to expect for `reasonml.org`, such as the new Reason Playground or the `doc-tools` project for extracting JSON data from module documentation in BuckleScript projects and we hope you are as excited as we are!

In case you have any questions or comments, make sure to let us know in the [Reason Discord](https://discord.gg/reasonml) `#docs` channel!

Happy documentation browsing!

## Upcoming Posts

**Part 4) It's all Opinions:**
We'll dive into our documentation philosophy, our vision of the Reason Platform and ideas on how to tackle the "Reason Native" documentation.

## Previous Posts

- > **Go to [Part 1](./state-of-reasonml-org-2020-q2-pt1.mdx)** if you haven't read it yet.
- **Part 2) [Higher Quality Docs](./state-of-reasonml-org-2020-q2-pt2.mdx)**
